<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--

 This library is part of OpenCms -
 the Open Source Content Management System

 Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 Lesser General Public License for more details.

 For further information about Alkacon Software GmbH & Co. KG, please see the
 company website: http://www.alkacon.com

 For further information about OpenCms, please see the
 project website: http://www.opencms.org

 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

-->
</head>
<body bgcolor="white">

<p>
This is the API description for the OpenCms core, please read the <a href="#intro">introdution</a> below to learn 
about the packages and functions of the API that are intended to be used in OpenCms application development.
</p>

<h2>Introduction<a name="intro"> </a>to the OpenCms API</h2>

<p>
The OpenCms API contains several building blocks:
</p>

<ul>
<li>The document repository, called <i>Virtual File System</i> (or just <i>VFS</i>).</li>
<li>The JSP based templating system.</li>
<li>The module API.</li>
<li>The main runtime system.</li>
<li>Several utility classes, for example for mail transport or scheduling.</li>
<li>A number of low level database connetion methods.</li>
<li>The OpenCms Workplace implementation.</li>
</ul>

<p>
Not all packages defined in this API are considered "end user" API functions.
For example, to access the OpenCms repository you should use an initialized instance of the 
<code>{@link org.opencms.file.CmsObject}</code> class, and never access the database directly with SQL.
So the database functionalities in the <code>org.opencms.db</code> package are 
"low level" functions, used by the classes in the <code>org.opencms.file</code> package
but usually not directly by an application.
</p>

<h2>How to start developing OpenCms applications</h2>

<p>
Here are some basic pointers that should help you identify importants 
parts in this API documentation that are usually required in OpenCms application development:
</p>

<p>
You should start with the template functions provided in the <code>org.opencms.jsp</code> package.
This contains the OpenCms <code>&lt;cms:&gt;</code> taglib, as well as the <code>{@link org.opencms.jsp.CmsJspActionElement}</code> 
(for use with scriptlets). 
These allow you to easliy access the current users <code>{@link org.opencms.file.CmsObject}</code> from a JSP, 
and with this you can dynamically build OpenCms front end applications based on the users permissions.
</p>

<p>
For easy template navigation building, check out the methods <code>{@link org.opencms.jsp.CmsJspNavBuilder}</code>.
You can build full-blown OpenCms applications with the functions from the <code>org.opencms.jsp</code> package 
and never bother about the rest of the API.
</p>

<p>
After you have mastered the basics of template development, you should take a closer look at the objects in the
<code>org.opencms.file</code> package. These object are the "building blocks" for OpenCms applications, 
and it certainly helps to understand these in greater detail before moving on to more complex OpenCms applications.
As already mentioned, the <code>{@link org.opencms.file.CmsObject}</code> is probably the most important class there.
</p>

<p>
In case you want to use certain OpenCms "operating system" features, use the <code>{@link org.opencms.main.OpenCms}</code> singleton to
gain access to the low level manager classes that handle the system runtime. 
</p>

<p>
The <code>org.opencms.module</code> package contains the OpenCms module API. 
You do not usually need to "program" a module because a module is most often created using the OpenCms Workplace.
However, in case you want to trigger certain module lifecyle events, have a look at the <code>{@link org.opencms.module.I_CmsModuleAction}</code>
interface.
</p>

<p>
There are a couple of utility functions worth to mention here:
In case you want to send emails from your application, check out the <code>org.opencms.mail</code> package.
You can schedule recurring operations in OpenCms by implementing the <code>{@link org.opencms.scheduler.I_CmsScheduledJob}</code>
interface.
</p>

<h2>The basic OpenCms application design</h2>

<p>
OpenCms runs as a multi tier application. 
The database layer that contains the VFS is accessed only through the business logic provided by the
<code>{@link org.opencms.file.CmsObject}</code> class. 
This runs totally independent 
of any servlet container, there is no database logic whatsoever in the "front end", for example the JSP templates. 
Check the <code>{@link org.opencms.main.CmsShell}</code> description to see how to access the VFS without a servlet container.
</p>

<p>
In normal operation, OpenCms runs as a servlet in a servlet container.
On the startup of the container, OpenCms initializes itself from the configuration provided in the XML files.
After the XML configuration has been read, a singleton instance of the <code>{@link org.opencms.main.OpenCms}</code>
object provides access to all OpenCms functionality.
This <code>{@link org.opencms.main.OpenCms}</code> singleton instance can be considered the "operating system" of OpenCms.
</p>

<p>
After the "operating system" is initialized and the <code>{@link org.opencms.main.OpenCms}</code> object is available,
all requestes made to the <code>{@link org.opencms.main.OpenCmsServlet}</code> are directly passed to this for authorization.
When a request is recieved, it's first authenticated to see which <code>{@link org.opencms.file.CmsUser}</code>
has made the request. If the user has not been authenticated so far, the <code>{@link org.opencms.file.CmsUser}</code> object
is initialized with "Guest" user permissions. 
With this user context, an instance of a <code>{@link org.opencms.file.CmsRequestContext}</code> is generated, and with that 
a <code>{@link org.opencms.file.CmsObject}</code> is initialized. 
This initialized <code>{@link org.opencms.file.CmsObject}</code>
then provides the "users context" for all access operations to the OpenCms VFS. 
It can also be considered the "shell" of the user to the OpenCms VFS. 
All access operations to the VFS are done through the <code>{@link org.opencms.file.CmsObject}</code>, and 
this means that all access operations automatically are done with the authenticated users permissions.
</p>

<!-- Put @see and @since tags down here. -->

</body>
</html>